Installation Notes for Sample ADS Web-based User Interface

The following are installation notes for the Automated Deployment Services Web-based User Interface (ADS Web).

Disclaimer

The sample code provided is covered under the terms of the end-user license agreement (EULA) displayed during setup.

Contents

● Installation

● ADS Web Advanced Features

● Working with Sample Code Using Visual Studio

● Customizing ADS Web

● Application Architecture Overview

● Known Issues

Installation

Prerequisites

· You must install the ADS Web sample code on an ADS controller running Microsoft® Windows® Server™ 2003, Enterprise Edition.

· You must have ASP.NET and Internet Information Services (IIS) components installed, and network COM+ access enabled on the server. (In Control Panel, in Add/Remove Programs, click Add/Remove Windows Components.)

· You should be comfortable using and administering ADS 1.0.

► To install the ADS Web-based interface

1. Run the installation file ADSWebSetup.msi.

2. Accept the EULA and all default settings.

3. Ensure that Anonymous Access is disabled for the ADS Web site. To disable anonymous access:

a. Under All Programs, select Administrative Tools, and then click Internet Information Services Manager.

b. In the IIS console, select Web Sites, select Default Web, and then click ADS Web. Right-click ADS Web, and then click Properties.

c. In the AdsWeb Properties dialog box, select the Directory Security tab. In the Authentication and access control area, click Edit.

d. In the Authentication Methods dialog box, uncheck the Enable anonymous access box, and then click OK.

4. Enter the URL http://localhost/adsweb to browse and explore the ADS Web site.

Installation Notes

● The first time you request an ADS Web page, it may take time to load. However, after this initial page load, you should not experience an excessive delay again.

● No estimated end times are available when you first run jobs. Several jobs must be run and completed before time estimates can be generated.

● Two features of the ADS Web use client-side scripting and Microsoft Active-X® controls to perform their operations. These features are:

· Mounting and unmounting images using the Web site

· All external commands from the Device> All Tasks menu

These features will fail on a default installation of Internet Explorer 5 if the security setting Initialize and script Active X controls not marked as safe is disabled.

► To change the browser setting and be able to use these features

1. Connect to the ADS Web site. (This ensures that you are in the correct security zone as the setting must be changed per security zone.)

2. Select Tools, select Internet Options, select the Security tab, and then click Custom Level.

3. Select the Prompt button under Initialize and script Active X controls not marked as safe.

● The default DeviceCommands.xml file contains references to external programs that may be installed on your system. See the All Tasks Menu for Devices for more information.

! Note: A default install of the ADSWeb will not function properly if loaded onto a domain controller. For non-production test and demo use, you can get ADSWeb to work on a domain controller by changing the identity of the default app pool from NetworkSystem to LocalSystem. This is not a secure configuration and is not recommended for production use.

ADS Web Advanced Features

ADS Web offers administrators several advanced features that can make their work easier.

ADS Controller as a Device

Administrators will find that ADS Web differs from the ADS Microsoft Management Console (MMC) snap-in by showing the ADS Controller as a visible device. This feature allows jobs and device variables to be defined for the Controller. This feature can be disabled.

► To disable showing the ADS Controller as a device

1. Navigate to the location of the Web site (for example, C:\inetpub\wwwroot\adsweb).

2. Open the Web.config file using notepad and find the section similar to the following:

</appSettings>

3. Change the value="true” to value=“false”.

4. Restart the Web site.

All Tasks Menu for Devices

Devices are right-click enabled throughout the ADS Web site. One of the menu items on this menu is the All Tasks menu. The menu is dynamically generated by reading an XML file called ‘DeviceCommands.xml’ in the root the Web site. The following is an example of the file.

<?xml version="1.0" encoding="utf-8" ?>

<command name="Open Remote Desktop"

command="MSTSC.EXE /v:$Device.System.Name$">

</command>

<command name="Open Remote Desktop by IP"

command="MSTSC.EXE /v:$Device.System.adminip$">

</command>

<command name="Open Computer Mgmt"

command="MMC.exe c:\\windows\\system32\\compmgmt.msc

/computer=$Device.System.adminip$">

</command>

<command name="CPQ Console Access"

command="explorer.exe https://$device.user.cpqribID$">

</command>

<command name="CPQ Power Off"

command="cmd /k c:\\cpq\\CPQLOCfg.exe -s

$device.user.cpqribID$ -f c:\\cpq\\PowerOff.xml -v">

</command>

<command name="CPQ Power On"

command="cmd /k c:\\cpq\\CPQLOCfg.exe -s

$device.user.cpqribID$ -´ c:\\cpq\\PowerOn.xml -v">

</command>

<command name="Debug Sample"

command="cmd /k echo Name:$Device.System.Name$

IP:$device.system.adminip$

Mac:$device.system.adminmac$ & pause">

</command>

</deviceCommands>

Note that each command entry has a name and then optional command parameters depending on the type of command required. For example, if the name of the command is "-," then a non-selectable horizontal line is added to the menu. Each command name must be unique. Duplicate command names will result in the wrong command being executed.

The following commands are available:

● External Programs

Any external command line program can be called by adding a command attribute. Here is an example.

<command name="Open Remote Desktop"

command="MSTSC.EXE /v:$Device.System.Name$">

</command>

This command will run the program terminal server and pass the name of the current device.

Device replacement variables follow the ADS replacement format where $<Variable>$ is used. The following table shows the recognized values

Name	Description
Device.System.Name	The name of the current device
Device.System.AdminIP	The admin IP address of the current device
Device.System.AdminMAC	The admin MAC address of the current device
Device.User.<Variable>	The value of any valid variable can be specified for <Variable>. This can be used to return any custom value required.

● Job Templates

An existing job template can be executed by adding the jobTemplate attribute. The jobTemplate must match the name of an existing job template. For example:

</command>

Working with Sample Code Using Visual Studio

Modifying ADS sample code to meet your purposes requires installing AdsDevWebSetup.msi. The process is similar to installing the ADSWebSetup.msi.

Note: You can install the two MSIs on the same computer or on different computers. However, if you install both MSIs on a single computer, do not then uninstall one or the other because they will share common components.

Prerequisites

● You must install the ADS Web sample code on an ADS controller running Windows Server 2003 Enterprise Edition

● You must have ASP.NET and IIS components installed and network COM+ access enabled on the server. (In Control Panel, Under Add/Remove Programs, click Add/Remove Windows Components.)

● Microsoft Visual Studio® 2003 is recommended for loading the ASP.NET solution and rebuilding the solution.

● You should be comfortable using and administering ADS 1.0.

● You should be familiar with ASP.NET, C# and .NET.

Installation

► To build the sample code using Visual Studio

1. Run the installation of AdsDevWebSetup.msi.

2. Accept the EULA and all default settings.

3. Ensure that Anonymous Access is disabled for the ADS Dev Web site. To disable Anonymous Access:

a. Under All Programs, select Administrative Tools, and then click Internet Information Services Manager.

b. In the IIS console, select Web Sites, select Default Web, and then click ADS Web. Right-click ADS Web, and then click Properties.

c. In the AdsWeb Properties dialog box, select the Directory Security tab. In the Authentication and access control area, click Edit.

d. In the Authentication Methods dialog box, uncheck the Enable anonymous access box, and then click OK.

Enter the URL http://localhost/adsdevweb to browse and explore the ADS Web site.

The source files for ADS Web are installed in C:\Program Files\Ads Web Development. A Visual Studio 2003 .sln file is located in the root of this folder. If Visual Studio 2003 is installed, double-clicking on this file will open the solution within Visual Studio 2003.

All code needs to be compiled before the ADS Web site reflects code modifications.

Customizing ADS Web

This section provides examples of how ADS Web can be customized.

Changing colors and images

The simplest form of customization does not require the Web site to be rebuilt and can be performed directly on the files in wwwroot/adsweb. Most colors and visual elements can be changed by updating the Style/adsweb.css file and changing images in the images directory. For example, the form header for each page is similar to the following:

This header is controlled by the style sheet and displays the default logo (logo.gif) in a portion of the style sheet is shown below.

.headerbackground

{

BACKGROUND-COLOR:#9c9cd8;

}

.headerlogo

{

background-position: left center;

background-image: url(../images/logo.gif);

background-repeat: no-repeat;

width:32px;

height:32px;

}

.pageheader

{

width:100%;

font-size:16pt;

color:white;

}

.pageheaderdescription

{

font-size:8pt;

color:White;

}

You can change the logo image by modifying this file. For example, using a new logo called my_logo.jpg, you could change the color and logo by modifying the .css file as follows:

.headerbackground

{

BACKGROUND-COLOR:#0000dd;

}

.headerlogo

{

background-position: left center;

background-image: url(../images/my_logo.jpg);

background-repeat: no-repeat;

width:32px;

height:32px;

}

.pageheader

{

width:100%;

font-size:16pt;

font-family: Comic Sans MS;

color:black;

}

.pageheaderdescription

{

font-size:8pt;

color:Black;

}

These changes would produce the following form header:

Changing Main Menu Items

The main menu items on the left-hand side of the screen are generated by the controls\menu.ascx control. This section introduces the menu.ascx control and covers how to make the following menu changes:

● Add a new menu item

● Ensure that a menu item is visible only to users in a specific group

Menu.ascx overview

This page uses library functions in the MenuUtils class to generate menu items. The menu is generated in the GetMenu function. Some common functions are mentioned below:

GetTitleRow

This function generates a new title row with the title and help URL.

MenuUtils.GetTitleRow(string item, string helpurl)

For example:

MenuUtils.GetTitleRow("Devices", "help.aspx")

would generate the following:

GetMenuRow

This function generates a normal menu row.

GetMenuRow(string item, string link, string target)

For example:

GetMenuRow(“Show”, “DeviceList.aspx”, “main_frame”)

would generate the following:

Clicking on this item would result in the DeviceList.aspx page being shown in the “main_frame” of the application.

Add a New Menu Item

► To add a menu item to show all devices in a new window

1. Assume that there is a set called Production.

2. Open Controls/menu.ascx.cs within Visual Studio 2003.

3. Find the GetMenu function and add the following line (an appropriate place to add this is after the set title).

Reponse.Write(

MenuUtils.GetMenuRow(

“Show Production”,

“SetDeviceList.aspx?set=Production”,

“blank”

)

);

Because the target is blank, the browser will open the Setdevicelist.aspx page in a new window. [KB1] Also, the SetDeviceList.aspx page takes a set name as an argument and, therefore, the set specified devices for the set will be shown.

Ensure That a Menu Item Is Visible Only to Users in a Specific Group

ASP.NET always has a current user when processing requests if Integrated Authentication is being used. The current user is the user requesting the page. You can select groups that the user is a member of and allow or disallow certain operations. One of the simplest (but not necessarily the most secure) operations is to hide the menu items relating the tasks you don’t wish the user to perform.

► To ensure that only device administrators are able to view and change devices

1. Create a new group called Device Admins and add the appropriate users to it.

2. Open Controls/menu.ascx.cs from within Visual Studio.

3. Find the part of GetMenu that creates the devices menu. Wrap it in the following if statement.

if(HttpContext.Current.User.IsInRole("DOMAIN\\Device Admins"))

{

Response.Write(MenuUtils.GetSpacer());

Response.Write(MenuUtils.GetTitleRow("Devices", …

…

}

Note that the devices menu should now only be shown if the current user is a member of the specified group. The \ in the group must be escaped within C#. Valid IsInRole names include:

● DOMAIN\Group Name

● MACHINE\Group Name

● BUILTIN\Group Name

Application Architecture Overview

There are four projects that make up the ADS Web solution:

● ADSWeb—This project is the ASP.NET Web site and is where most customization will occur. It is described in the Customizing ADS Web section.

● AdsLibrary—This project provides a library of functions that is used to interact with the ADS controller via the built-in .NET class System.Management and WMI. The library provides an easy type-safe wrapper around the basic WMI calls provided by ADS.

● Win32Security—This library is used to interact with Win32 Security Descriptors. It provides a simple method editing and updating security information stored in internal formats.

● ADSWebSetup—This project is not part of the Development Configuration. It is normally only built on demand. (It can be build by right-clicking on the project and selecting Build…). This project builds a new MSI you can use to deploy custom versions of ADS Web.

Directory structure of the ADS Web site

The following diagram shows the directory structure and interaction between the projects:

ADSWeb Root - All main Web pages

bin - All complied binary files

controls - All common controls used by the system.

images - All images used by the system

history - Images used for the state of history items.

jobstate - Images used to denote each state of a job.

js - All client side script

style - All style sheets for the Web site

library - Source for library functions used by the Web site

Known Issues

● Issues occur when Set Names with special characters are used with ADS Web

Set Names in the ADS MMC can contain any character. This causes issues when the Set Names are used in JavaScript and as part of URL. Set Names should be limited to the same set of characters as device names: [A-Z][a-z][0-9]_-[space].

● Uninstall problems occur when both runtime and development MSIs are installed

When both runtime and development MSIs are installed on the same computer, uninstalling one of the MSIs will remove common components, requiring the remaining MSI to be reinstalled.

Send feedback on “Installation Notes for Sample ADS Web-based User Interface”